<?php
/** 
 * 
 *
 * @package api
 * @subpackage collections
 * @author $Author$
 * @version $Id: Collection.php 14 2006-11-28 22:05:19Z rdff3 $
 */
/**
 *
 */
require_once( "lang/Object.php" );
require_once( "lang/Iterable.php" );

/**
 * Interface Collection
 *
 * The root interface in the <i>collection hierarchy</i>. A collection represents a group of objects, known as its <i>elements</i>. 
 * Some collections allow duplicate elements and others do not. Some are ordered and others unordered. 
 * The JDK does not provide any <i>direct</i> implementations of this interface: it provides implementations of more specific 
 * subinterfaces like {@link Set} and {@link List}. This interface is typically used to pass collections around 
 * and manipulate them where maximum generality is desired.
 *
 * <i>Bags</i> or <i>multisets</i> (unordered collections that may contain duplicate elements) should implement this interface directly.
 * 
 * All general-purpose {@link Collection} implementation classes (which typically implement {@link Collection} indirectly 
 * through one of its subinterfaces) should provide one "standard" constructor: a void (no arguments) constructor, which creates an empty 
 * collection.
 *
 * The "destructive" methods contained in this interface, that is, the methods that modify the collection on which they operate, 
 * are specified to throw {@link UnsupportedOperationException} if this collection does not support the operation. If this is 
 * the case, these methods may, but are not required to, throw an {@link UnsupportedOperationException} if the invocation 
 * would have no effect on the collection. For example, invoking the {@link addAll Collection::addAll()} method on an 
 * unmodifiable collection may, but is not required to, throw the exception if the collection to be added is empty.
 *
 * Some collection implementations have restrictions on the elements that they may contain. For example, some implementations 
 * prohibit null elements, and some have restrictions on the types of their elements. Attempting to add an ineligible element 
 * throws an unchecked exception, typically {@link NullPointerException} or {@link ClassCastException}. Attempting to query the 
 * presence of an ineligible element may throw an exception, or it may simply return false; some implementations will exhibit the 
 * former behavior and some will exhibit the latter. More generally, attempting an operation on an ineligible element whose completion
 * would not result in the insertion of an ineligible element into the collection may throw an exception or it may succeed, at the option
 * of the implementation. Such exceptions are marked as "optional" in the specification for this interface.
 *
 * This interface is a member of the PHP Collections Framework.
 *
 * Many methods in Collections Framework interfaces are defined in terms of the {@link equals} method. For example, the specification 
 * for the {@link contains Collection::contains()} method says: "returns true if and only if this collection contains at least one 
 * element e such that (o==null ? e==null : o->equals(e))." This specification should not be construed to imply that invoking 
 * {@link contains} with a non-null argument o will cause o->equals(e) to be invoked for any element e. Implementations are free 
 * to implement optimizations whereby the equals invocation is avoided, for example, by first comparing the hash codes of the 
 * two elements. 
 * (The {@link hashCode Object::hashCode()} specification guarantees that two objects with unequal hash codes cannot be equal.) 
 * More generally, implementations of the various Collections Framework interfaces are free to take advantage of the specified behavior of
 * underlying Object methods wherever the implementor deems it appropriate. 
 *
 * @package api
 * @subpackage collections
 * @author $Author$
 * @version $Id: Collection.php 14 2006-11-28 22:05:19Z rdff3 $
 */
interface Collection extends Iterable {
	/**
	 * Ensures that this collection contains the specified element.
	 * 
	 * Ensures that this collection contains the specified element.  Returns true if this collection changed as a result of the call. 
	 * (Returns false if this collection does not permit duplicates and already contains the specified element.)
	 *
	 * Collections that support this operation may place limitations on what elements may be added to this collection.  In particular,
	 * some collections will refuse to add null elements, and others will impose restrictions on the types of elements
	 * that may be added.  Collection classes should clearly specify in their documentation any restrictions on what elements may
	 * be added.
	 *
	 * If a collection refuses to add a particular element for any reason other that that it already contains the element, it <i>must</i>
	 * throw an exception (rather than returning false).  This preserves the invariant that a collection always contains the
	 * specified element after this call returns.
	 *
	 * @param Object $o element whose presence in this collection is to be ensured.
	 * @returns boolean true if this collection changed as a result of the call
	 * @throws {@link UnsupportedOperationException} - add is not supported by this collection.
	 * @throws {@link ClassCastException} - class of the specified element prevents it from being added to this collection.
	 * @throws {@link NullPointerException} - if the specified element is null and this collection does not support null elements.
	 * @throws {@link IllegalArgumentException} - some aspect of this element prevents it from being added to this collection.
	 */
	public function add( Object $o );
	
	/**
	 * Adds all of the elements in the specified collection to this collection.
	 * 
	 * Adds all of the elements in the specified collection to this collection. The behavior of this operation is undefined if the
	 * specified collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined
	 * if the specified collection is this collection, and this collection is nonempty.)
	 *
	 * @param Collection $c elements to be inserted into this collection.
	 * @returns boolean true if this collection changed as a result of the call
	 * @throws {@link UnsupportedOperationException} - if this collection does not support the {@link addAll} function.
	 * @throws {@link ClassCastException} - if the class of an element of the specified collection prevents it from being 
	 * 		added to this collection
	 * @throws {@link NullPointerException} - if the specified collection contains one ore more null elements and this 
	 * 		collection does not support null elements, or if the specified collection is null.
	 * @throws {@link IllegalArgumentException} - some aspect of an element of the specified collection prevents it from 
	 * 		being added to this collection.
	 * @see add()
	 */
	public function addAll( Collection $c );
	
	/**
	 * Removes all of the elements from this collection.
	 *
	 * Removes all of the elements from this collection.  This collection will be empty after this method returns unless it throws an
	 * exception.
	 *
	 * @throws {@link UnsupportedOperationException}- if the {@link clear} method is not supported by this collection.
	 */
	public function clear();
	
	/**
	 * Returns true if this collection contains the specified element.
	 *
	 * Returns true if this collection contains the specified element.  More formally, returns true if and only if this collection
	 * contains at least one element e such that (o==null ? e==null : o->equals(e)).
	 *
	 * @param Object $o element whose presence in this collection is to be tested.
	 * @returns boolean true if this collection contains the specified element
	 * @throws {@link ClassCastException} - if the type of the specified element is incompatible with this collection (optional)
	 * @throws (@link NullPointerException} - if the specified element is null and this collection does not support 
	 * 		null elements (optional).
	 */
	public function contains( Object $o );
	
	/** 
	 * Returns true if this collection contains all of the elements in the specified collection.
	 *
	 * @param Collection $c collection to be checked for containment in this collection
	 * @returns boolean true if this collection contains all of the elements in the specified collection.
	 * @throws {@link ClassCastException} - if the types of one or more elements in the specified collection are 
	 * 		incompatable with this collection (optional).
	 * @throws {@link NullPointerException} - if the specified collection contains one or more null elements and 
	 * 		this collection does not support null elements (optional).
	 * @throws {@link NullPointerException} - if the specified collection is null
	 * @see contains()
	 */
	public function containsAll( Collection $c );
	
	/** 
	 * Compares the specified object with this collection for equality.
	 *
	 * While the Collection interface adds no stipulations to the general contract for the Object.equals, programmers who 
	 * implement the Collection interface "directly" (in other words, create a class that is a Collection but is not a 
	 * Set or a List) must exercise care if they choose to override the Object.equals. It is not necessary to do so, and 
	 * the simplest course of action is to rely on Object's implementation, but the implementer may wish to implement a 
	 * "value comparison" in place of the default "reference comparison." (The List and Set interfaces mandate such value 
	 * comparisons.)
	 *
	 * The general contract for the {@link Object::equals() Object->equals} method states that equals must be symmetric 
	 * (in other words, a->equals(b) if and only if b->equals(a)). The contracts for {@link List::equals() List->equals} and 
	 * {@link Set::equals() Set->equals} state that lists are only equal to other lists, and sets to other sets. Thus, a custom 
	 * equals method for a collection class that implements neither the {@link List} nor {@link Set} interface must return false 
	 * when this collection is compared to any list or set. (By the same logic, it is not possible to write a class that 
	 * correctly implements both the Set and List interfaces.)
	 *
	 * @param Object $o Object to be compared for equality with this collection
	 * @returns boolean true if the specified object is equal to this collection
	 * @see Object::equals(), Set::equals(), List::equals()
	 */
	public function equals( Object $o);
	
	/**
	 * Returns the hash code value for this collection.  
	 * 
	 * Returns the hash code value for this collection. While the {@link Collection} interface adds no stipulations to the general
	 * contract for the {@link Object::hashCode()} method, programmers should take note that any class that overrides the 
	 * Object.equals  method must also override the Object.hashCode method in order to satisfy the general contract for 
	 * the Object.hashCode method. In particular, c1.equals(c2) implies that c1.hashCode()==c2.hashCode().
	 *
	 * @returns int the hash code value for this collection.
	 * @see Object::hashCode(), Object::equals()
	 */
	public function hashCode();
	
	/**
	 * Returns true if this collection contains no elements.
	 *
	 * @returns boolean true if this collection contains no elements.
	 */
	public function isEmpty();

	/**
	 * Removes a single instance of the specified element from this collection, if it is present.
	 *
	 * Removes a single instance of the specified element from this collection, if it is present (optional operation). 
	 * More formally, removes an element e such that (o==null ? e==null : o.equals(e)), if this collection contains one 
	 * or more such elements. Returns true if this collection contained the specified element (or equivalently, if this 
	 * collection changed as a result of the call).
	 * 
	 * @param Object $o element to be removed from this collection, if present.
	 * @returns boolean true if this collection changed as a result of the call.
	 * @throws {@link ClassCastException} - if the type of the specified element is incompatible with this collection (optional).
	 * @throws {@link NullPointerException} - if the specified element is null and this collection does not support 
	 * 		null elements (optional).
	 * @throws {@link UnsupportedOperationException} - remove is not supported by this collection.
	 */
	public function remove( Object $o );
	
	/**
	 * Removes all this collection's elements that are also contained in the specified collection.
	 *
	 * Removes all this collection's elements that are also contained in the specified collection (optional operation). 
	 * After this call returns, this collection will contain no elements in common with the specified collection.
	 *
	 * @param Collection $c elements to be removed from this collection.
	 * @returns boolean true if this collection changed as a result of the call.
	 * @throws {@link ClassCastException} - if the types of one ore more elements in this collection are incompatible 
	 * 		with the specified collection (optional).
	 * @throws {@link NullPointerException} - if the specified element is null and this collection does not support null 
	 * 		elements (optional).
	 * @throws {@link NullPointerException} - if the specified collection is null
	 * @throws {@link UnsupportedOperationException} - if the removeAll method is not supported by this collection.
	 */
	public function removeAll( Collection $c );
	
	
	/**
	 * Retains only the elements in this collection that are contained in the specified collection.
	 *
	 * Retains only the elements in this collection that are contained in the specified collection (optional operation). 
	 * In other words, removes from this collection all of its elements that are not contained in the specified collection.
	 *
	 * @param Collection $c elements to be retained in this collection.
	 * @returns boolean true if this collection changed as a result of the call.
	 * @throws {@link ClassCastException} - if the types of one ore more elements in this collection are incompatible 
	 * 		with the specified collection (optional).
	 * @throws {@link NullPointerException} - if this collection contains one or more null elements and the specified 
	 * 		collection does not support null elements (optional).
	 * @throws {@link NullPointerException} - if the specified collection is null
	 * @throws {@link UnsupportedOperationException} - if the retainAll method is not supported by this collection.
	 */
	public function retainAll( Collection $c );
	
	/**
	 * Returns the number of elements in this collection.
	 *
	 * @returns int the number of elements in this collection
	 */
	public function size();
	
	/**
	 * Returns an array containing all of the elements in this collection. 
	 *
	 * If the collection makes any guarantees as to what order its elements are returned by its iterator, this method 
	 * must return the elements in the same order.
	 * 
	 * This method acts as bridge between array-based and collection-based APIs. 
	 *
	 * @returns array an array containing all of the elements in this collection
	 */
	public function toArray();
}



?>